# -*- coding: utf-8 -*-
#
# Copyright 2009 Vanderbilt University
# 
# Licensed under the Apache License, Version 2.0 (the "License"); 
# you may not use this file except in compliance with the License. 
# You may obtain a copy of the License at 
# 
#     http://www.apache.org/licenses/LICENSE-2.0 
# 
# Unless required by applicable law or agreed to in writing, software 
# distributed under the License is distributed on an "AS IS" BASIS, 
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
# See the License for the specific language governing permissions and 
# limitations under the License. 

"""Database API for HORNET.  Allows simplified interaction with `many relational
database systems <http://www.sqlalchemy.org/docs/05/dbengine.html#supported-dbapis>`_.

:mod:`hornet.db` is a simple wrapper for `SQLAlchemy <http://www.sqlalchemy.org>`_.

Create an in-memory database, using :func:`hornet.db.create_engine`:

>>> db = create_engine('sqlite://')

Establish a connection:

>>> conn = db.connect()

Create some test data:

>>> r = conn.execute('CREATE TABLE test (id INTEGER)')
>>> r = conn.execute('INSERT INTO test VALUES (23)')

Perform a select from the new table and print the results:

>>> result = conn.execute('SELECT * FROM test')
>>> for r in result: print r
(23,)

You should always make sure you close the connection, preferably in a finally
block:

>>> conn.close()


.. moduleauthor:: John Paulett <john.paulett -at- vanderbilt.edu>
"""

from sqlalchemy import create_engine
